Providers

Providers connect BindAI agents to language models. BindAI separates agent configuration from the underlying model provider so applications can select different model providers without changing the overall agent architecture. The provider layer handles provider-specific model integration while the agent layer provides a consistent application-facing interface.

Provider Architecture

The relationship between an application, agent, provider, and model can be represented as:

Application
    |
    v
  Agent
    |
    v
 Provider
    |
    v
Language Model

The provider is responsible for communicating with the underlying model service. The exact capabilities available during execution depend on the provider and model being used.

Supported Providers

The current BindAI provider ecosystem includes:

OpenAI
Anthropic
Google Gemini
Groq
Ollama
OpenRouter

Provider integrations are registered with the BindAI provider registry. The registry provides a common interface for discovering and creating supported provider implementations.

Configuring a Model

The recommended way to select a model is through Agent.builder().

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

The model string uses the following format:

provider:model

For example:

openai:gpt-4.1-mini

The provider prefix identifies the provider, while the remaining value identifies the model.

Provider-Qualified Models

Provider-qualified model names allow the application to select a provider and model through a single configuration value. For example:

.model("openai:gpt-4.1-mini")

The same agent architecture can use another provider:

.model("anthropic:claude-sonnet-4")

or:

.model("google:gemini-2.5-flash")

or:

.model("groq:llama-3.3-70b-versatile")

or a locally hosted Ollama model:

.model("ollama:llama3")

or an OpenRouter model:

.model("openrouter:openai/gpt-4.1-mini")

The exact model identifier must be available through the selected provider.

Environment Variables

Provider credentials should not be hardcoded into application source code. For example:

OPENAI_API_KEY=your_api_key_here

The current BindAI development environment supports provider credentials such as:

OPENAI_API_KEY=your_api_key_here
ANTHROPIC_API_KEY=your_api_key_here
GEMINI_API_KEY=your_api_key_here
GROQ_API_KEY=your_api_key_here
OPENROUTER_API_KEY=your_api_key_here

Ollama generally runs locally and does not require a hosted-provider API key. Store sensitive configuration in environment variables or an appropriate secret-management system. Never commit API keys or other credentials to source control.

OpenAI

OpenAI models can be selected using the openai provider prefix.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

The selected model must be available to the configured OpenAI account. OpenAI can be used with the standard BindAI agent interface, including supported tool-calling, structured-output, and streaming execution features.

Anthropic

Anthropic models can be selected using the anthropic provider prefix.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("anthropic:claude-sonnet-4")
    .instructions("You are a helpful assistant.")
    .build()
)

The selected model must be available to the configured Anthropic account. Provider and model capabilities should be verified before relying on features such as tool calling or structured output.

Google Gemini

Google Gemini models can be selected using the google provider prefix.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("google:gemini-2.5-flash")
    .instructions("You are a helpful assistant.")
    .build()
)

The selected Gemini model must be available through the configured Google account and provider configuration.

Groq

Groq models can be selected using the groq provider prefix.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("groq:llama-3.3-70b-versatile")
    .instructions("You are a helpful assistant.")
    .build()
)

Groq provides hosted inference for supported models. The exact model identifier should match a model available through the configured Groq service.

Ollama

Ollama models can be selected through the ollama provider prefix.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("ollama:llama3")
    .instructions("You are a helpful assistant.")
    .build()
)

This allows an application to use a locally hosted model while keeping the agent configuration otherwise similar. The selected model must be available in the local Ollama environment. Ollama is useful when local inference is preferred for development, privacy, or deployment requirements.

OpenRouter

OpenRouter models can be selected through the openrouter provider prefix.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("openrouter:openai/gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

OpenRouter provides access to models through its routing service. The model identifier should match the model supported by the configured OpenRouter account.

Provider Registry

BindAI maintains a provider registry for supported provider implementations. The registry can expose the names of registered providers:

from bindai_providers import ProviderRegistry

print(ProviderRegistry.names())

The registry provides a common mechanism for provider registration and discovery. The current registered providers are:

anthropic
google
groq
ollama
openai
openrouter

Provider registration is handled by the BindAI provider bootstrap process.

Provider Bootstrap

BindAI initializes supported provider integrations through provider bootstrap. The CLI initializes the provider ecosystem before running the application. Conceptually:

BindAI CLI
    |
    v
Provider Bootstrap
    |
    +---- OpenAI
    +---- Anthropic
    +---- Google
    +---- Groq
    +---- Ollama
    +---- OpenRouter

This keeps provider registration modular and allows individual provider packages to be maintained independently.

Provider and Agent Configuration

Provider configuration and agent behavior are separate concerns. For example:

agent = (
    Agent.builder()
    .name("researcher")
    .model("openai:gpt-4.1-mini")
    .instructions(
        """
        You are a research assistant.

        Provide concise, factual answers.
        """
    )
    .build()
)

Here:

model() selects the provider and model.
instructions() defines agent behavior.
build() creates the configured agent.

This separation makes it possible to change the model configuration without rewriting the agent’s behavioral instructions.

Switching Providers

Because the model is configured through the agent builder, changing providers can often be as simple as changing the model string. For example:

.model("openai:gpt-4.1-mini")

can be changed to:

.model("anthropic:claude-sonnet-4")

or:

.model("ollama:llama3")

The rest of the agent configuration can remain conceptually unchanged. However, provider portability does not guarantee identical behavior between models.

Provider and Tools

Providers work together with BindAI’s tool system. For example:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .tools(search_tool, calculator_tool)
    .build()
)

The agent can then make use of registered tools during execution when supported by the underlying model and provider. Provider and model capabilities determine which tool-calling features are available. Applications should verify the capabilities of the selected model before depending on tool calling.

Provider and Structured Output

BindAI agents can request structured output through run(). For example:

from pydantic import BaseModel


class User(BaseModel):
    name: str
    age: int


result = agent.run(
    "Generate a fictional user.",
    output=User,
)

print(result.output)

The actual structured-output behavior depends on the capabilities and implementation of the configured provider and model. Applications should test structured-output behavior with the provider/model combinations they intend to support.

Provider and Streaming

BindAI exposes streaming APIs for agent execution. For conversational streaming:

for chunk in agent.stream_chat("Explain transformers."):
    print(chunk)

The exact streaming behavior depends on the execution API and provider implementation. Streaming is particularly useful for:

Chat interfaces
Interactive applications
Long responses
Real-time user experiences

Provider and Memory

Memory is implemented at the BindAI agent/application layer rather than being tied to a particular model provider. For example:

agent = Agent.builder().name("assistant").model("openai:gpt-4.1-mini").memory(memory).build()

The same general memory configuration can be used while changing the model provider. This separation allows model selection and application state management to evolve independently.

Provider and Knowledge

Knowledge and retrieval are also separate from the provider implementation. For example:

agent = (
    Agent.builder()
    .name("researcher")
    .model("openai:gpt-4.1-mini")
    .knowledge(knowledge)
    .retriever(retriever)
    .build()
)

The knowledge system retrieves relevant information while the configured provider supplies the language model used for the agent execution. This separation allows the same knowledge architecture to be used with different model providers.

Local Models

One advantage of the provider abstraction is that applications can use local inference services. For example:

.model("ollama:llama3")

The rest of the agent can retain the same general structure:

agent = (
    Agent.builder()
    .name("assistant")
    .model("ollama:llama3")
    .instructions("You are a helpful assistant.")
    .build()
)

This makes it possible to experiment with local models without restructuring the application around a provider-specific SDK.

Custom Providers

BindAI exposes provider abstractions that allow additional provider implementations to be integrated into the framework. The provider ecosystem is designed around common provider interfaces and registration. Custom provider implementations should follow the provider interfaces exposed by the BindAI version being used. Because provider APIs can evolve independently, consult the provider implementation and API reference when developing a custom integration.

Provider Independence

Provider independence means that the application-level agent interface is separated from provider-specific model communication. For example, the application can construct an agent using:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

The model can later be changed:

.model("ollama:llama3")

without requiring the rest of the application to be rewritten around a provider-specific SDK. This is one of the primary benefits of the provider abstraction.

Provider Portability

The provider-qualified model format allows the same general agent architecture to be used with different providers. For example:

.model("openai:gpt-4.1-mini")

.model("anthropic:claude-sonnet-4")

.model("google:gemini-2.5-flash")

.model("groq:llama-3.3-70b-versatile")

.model("ollama:llama3")

.model("openrouter:openai/gpt-4.1-mini")

The agent’s tools, instructions, memory, knowledge, and workflow integration can remain conceptually separate from provider selection. However, provider portability does not mean that every model supports every capability. Always verify the capabilities of the selected model before relying on features such as:

Tool calling
Structured output
Streaming
Particular context limits
Provider-specific features

Choosing a Provider

The appropriate provider depends on the application’s requirements. Consider:

Model capabilities
Hosting requirements
Privacy requirements
Latency
Cost
Tool-calling support
Structured-output support
Streaming support
Deployment environment
Local versus hosted inference

For local development or local inference, Ollama can be useful. For hosted applications, a managed provider or routing service may be more appropriate. The best provider is therefore determined by the requirements of the application rather than by provider popularity alone.

Provider Configuration in Development

A typical development environment can keep provider credentials in a .env file. For example:

OPENAI_API_KEY=your_api_key_here
ANTHROPIC_API_KEY=your_api_key_here
GEMINI_API_KEY=your_api_key_here
GROQ_API_KEY=your_api_key_here
OPENROUTER_API_KEY=your_api_key_here

Applications should load environment configuration through their normal configuration mechanism. Never commit the .env file when it contains real credentials. A project can also configure only the provider credentials it actually needs.

Provider Errors

Provider execution can fail for reasons such as:

Invalid credentials
Missing credentials
Unsupported model
Provider service errors
Network failures
Rate limits
Invalid requests
Insufficient provider account credits

Applications should use the AgentResult returned by agent execution to determine whether an execution succeeded. For example:

result = agent.run("Explain what BindAI is.")

if result.success:
    print(result.output)
else:
    print(result.error)

Provider-specific failures should not require the application to replace the overall agent abstraction.

Provider Testing

Provider integrations should be tested independently as well as through agent execution. Useful tests include:

Provider registration
Provider discovery
Model creation
Authentication configuration
Tool calling
Structured output
Streaming
Error handling

Not every provider/model combination supports every capability identically, so integration tests should reflect the capabilities the application actually requires.

Complete Example

A complete agent can use the provider abstraction together with other BindAI capabilities:

from bindai import Agent


agent = (
    Agent.builder()
    .name("research-assistant")
    .model("openai:gpt-4.1-mini")
    .instructions(
        """
        You are a research assistant.

        Provide clear and concise answers.
        Use available tools and knowledge when appropriate.
        """
    )
    .tool(search)
    .memory(memory)
    .knowledge(knowledge)
    .retriever(retriever)
    .build()
)

result = agent.run("Research BindAI and summarize its architecture.")

if result.success:
    print(result.output)
else:
    print(result.error)

The provider can then be changed without fundamentally changing the rest of the agent configuration:

.model("anthropic:claude-sonnet-4")

or:

.model("ollama:llama3")

This demonstrates the separation between provider selection and application-level agent configuration.

Best Practices

Keep provider credentials out of source code.
Use environment variables or an appropriate secret-management system for credentials.
Use the provider:model format when selecting a model.
Prefer Agent.builder() for agent configuration.
Keep provider-specific logic out of application-level business logic where practical.
Verify model capabilities before relying on tool calling or structured output.
Test provider/model combinations used by the application.
Use local providers when local inference is appropriate.
Choose models based on the actual requirements of the task.
Keep provider configuration separate from agent instructions whenever possible.
Do not assume that different providers will produce identical behavior.
Keep provider integrations modular so additional providers can be added without changing the core agent abstraction.

BindAI’s provider architecture gives applications a consistent agent interface while allowing the underlying model provider to change as requirements evolve.

​Providers

​Provider Architecture

​Supported Providers

​Configuring a Model

​Provider-Qualified Models

​Environment Variables

​OpenAI

​Anthropic

​Google Gemini

​Groq

​Ollama

​OpenRouter

​Provider Registry

​Provider Bootstrap

​Provider and Agent Configuration

​Switching Providers

​Provider and Tools

​Provider and Structured Output

​Provider and Streaming

​Provider and Memory

​Provider and Knowledge

​Local Models

​Custom Providers

​Provider Independence

​Provider Portability

​Choosing a Provider

​Provider Configuration in Development

​Provider Errors

​Provider Testing

​Complete Example

​Best Practices